plugins - 插件

Auto.js提供了加载插件的机制，允许用户编写带有Activity, Service, C/C++库等的apk，安装到Android设备上，并用Auto.js加载和调用。

一个插件是一个可独立安装的apk文件，用户安装后，再通过$plugins模块加载插件和调用其中的API。

从Pro 9.2开始，插件支持打包时合并到apk中，打包后无需再单独安装插件。

提示

Pro 9.2中，Auto.js Pro应用内置了插件商店，现在可在插件商店下载插件，参见博客Auto.js Pro 9.2版本正式发布。

$plugins.load(packageName)

• packageName {string} 加载的插件包名

加载一个插件，并返回插件模块中module.exports导出的对象。

如果插件未安装，则抛出PluginLoadException异常。

以下为一个OCR插件的使用例子：(插件下载地址参见OCR插件，从Pro 9.2开始不推荐使用该插件，官方内置了更强的OCR插件)。

requestScreenCapture();

let OCR = $plugins.load('org.autojs.plugin.ocr');
let ocr = new OCR();
// 截取屏幕并对屏幕文字进行识别，返回识别结果
console.log(ocr.ocrScreen());

如何开发一个插件

提示

以下示例代码可在这里找到完整项目：插件SDK

本示例中的包名均为org.autojs.plugin.sdk.demo，在实际项目中插件包名可能有所不同。

插件SDK集成

新建一个Android项目，在项目的build.gradle文件中添加：

allprojects {
    repositories {
        // ...
        maven { url 'https://jitpack.io' }
    }
}

在具体模块(比如app)的build.gradle文件中添加：

dependencies {
    // ... 
    implementation 'com.github.hyb1996:Auto.js-Plugin-SDK:0.2'
}

更多信息参见Jitpack.io。

插件配置

1. 新建PluginHelloWorld文件，继承于Plugin.

public class PluginHelloWorld extends Plugin {

    public PluginHelloWorld(Context context, Context selfContext, Object runtime, Object topLevelScope) {
        super(context, selfContext, runtime, topLevelScope);
    }

    // 返回插件的JavaScript胶水层代码的assets目录路径
    @Override
    public String getAssetsScriptDir() {
        return "plugin-helloworld";
    }

    // 插件public API，可被JavaScript代码调用
    public String getStringFromJava() {
        return "Hello, Auto.js!";
    }

    // 插件public API，可被JavaScript代码调用
    public void say(String message) {
        getSelfContext().startActivity(new Intent(getSelfContext(),  HelloWorldActivity.class)
                .putExtra("message", message)
                .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK));
    }
}

2. 新增MyPluginRegistry文件，继承于PluginRegistry:

public class MyPluginRegistry extends PluginRegistry {

    static {
        // 注册默认插件
        registerDefaultPlugin(new PluginLoader() {
            @Override
            public Plugin load(Context context, Context selfContext, Object runtime, Object topLevelScope) {
                return new PluginHelloWorld(context, selfContext, runtime, topLevelScope);
            }
        });
    }
}

在AndroidManifest.xml中配置以下meta-data, name为"org.autojs.plugin.sdk.registry"，value为MyPluginRegistry的包名。

  <application
        ...>

        <meta-data
            android:name="org.autojs.plugin.sdk.registry"
            android:value="org.autojs.plugin.sdk.demo.MyPluginRegistry" />

        <activity
            android:name=".HelloWorldActivity"
            android:exported="true" />

        <service
            android:name=".HelloworldPluginService"
            android:exported="true" />
    </application>

3. 编写JavaScript胶水层

在assets的相应目录(由Plugin.getAssetsScriptDir返回)中添加index.js文件，用于作为胶水层导出插件API。

module.exports = function (plugin) {
    let runtime = plugin.runtime;
    let scope = plugin.topLevelScope;

    function helloworld() {
    }

    helloworld.stringFromJava = plugin.getStringFromJava();

    helloworld.say = function (message) {
        plugin.say(message);
    }

    return helloworld;
}

4. 在Auto.js Pro中调用

编译插件为apk(assembleDebug/assembleRelease)，安装到设备上。在Auto.js Pro中使用以下代码调用：

let helloworld = $plugins.load("org.autojs.plugin.sdk.demo");
console.log(helloworld.stringFromJava);
helloworld.say("Hello, Auto.js Pro Plugin");

5. 独立服务AIDL方式调用

可以在插件中编写一个Service，由Auto.js Pro唤起和绑定，并可在js中通过aidl调用Service的接口。

在Plugin中重写方法getService。

// 插件服务类，可选，用于AIDL方式和Auto.js Pro本体通信。可返回null
@Override
public ComponentName getService() {
    return new ComponentName(getSelfContext().getPackageName(), HelloworldPluginService.class.getName());
}

新建一个Service组件（注意在AndroidManifest中注册时需要是exported="true")，继承于PluginService。

public class HelloworldPluginService extends PluginService {
    private static final String ACTION_ADD = "add";

    @Override
    protected Result onRemoteCall(@NonNull String action, @NonNull Map<String, Object> args, @Nullable RemoteCallback callback) throws RuntimeException {
        switch (action) {
            case ACTION_ADD:
                return invokeAdd(args);
        }
        return Result.notImplemented(action);
    }

    private Result invokeAdd(Map<String, Object> args) {
        Number a   = PluginUtils.getNotNull(args, "a");
        Number b   = PluginUtils.getNotNull(args, "b");
        double sum = a.doubleValue() + b.doubleValue();
        return new Result(Collections.singletonMap("sum", sum));
    }
}

在index.js中添加胶水层代码:

helloworld.remoteAdd = function (a, b) {
    return plugin.waitForConnection().call('add', {
        a: a,
        b: b
    }, null).get('sum');
}

然后可以在Auto.js Pro中调用：

let helloworld = $plugins.load("org.autojs.plugin.sdk.demo");
console.log(helloworld.remoteAdd(1, 2));

OCR插件

目前Auto.js官方仅提供一个简单的OCR插件作为示例，其效率相对较慢，仅为参考。该插件仅支持32位，Pro 9以上可能无法使用，推荐用官方内置ocr模块代替。

注意

从Pro 9.2开始不推荐使用该插件，官方内置了更强的OCR插件，比如内置$ocr模块和MLKit OCR插件。

OCR插件下载(密码: 4fw3)

new OCR([dataFile, lang])

• dataFile {string} 数据路径
• lang {string} 语言

创建一个新的OCR对象。OCR插件使用Tesseract为引擎。构造函数的dataFile和lang参数用于使用指定的语言模型初始化Tesseract引擎。

数据路径dataFile必须是tessdata的父目录的路径，并且必须以/结尾。最后一个/之后的任何路径都将被忽略。

要加载多种语言，例如，hin + eng将加载北印度语和英语。

更多信息参见TessBaseAPI。

使用自带的中文字库数据初始化OCR：

let OCR = $plugins.load('org.autojs.plugin.ocr');
let ocr = new OCR();

使用自己的数据初始化OCR：

let OCR = $plugins.load('org.autojs.plugin.ocr');
let ocr = new OCR("/sdcard/tessdata/", "chi_sim");

OCR.ocrFile(path)

• path {string} 文件路径
• 返回 OcrResult

对图片文件path进行OCR识别，返回识别后的结果。

let OCR = $plugins.load('org.autojs.plugin.ocr');
let ocr = new OCR();
$events.on('exit', () => {
    ocr.end();
});

let result = ocr.ocrFile($file.path('./image.png'));
console.log(result);

OCR.ocrImage(img)

• img {Image} Auto.js的图片对象，通过·$images·模块截图或者读取文件返回的对象
• 返回 OcrResult

对图片img进行OCR识别，返回识别后的结果。

requestScreenCapture();

let OCR = $plugins.load('org.autojs.plugin.ocr');
let ocr = new OCR();
$events.on('exit', () => {
    ocr.end();
});

let result = ocr.ocrImage(captureScreen());
console.log(result);

OCR.ocrScreen()

• 返回 OcrResult

截取当前屏幕进行OCR识别，返回识别后的结果。需要先申请截图权限。

OCR.ocrBitmap(bitmap)

• bitmap {Bitmap} android.graphics.Bitmap对象
• 返回 OcrResult

对图片bitmap进行OCR识别，返回识别后的结果。

OCR.end()

结束OCR识别，回收相应的OCR对象。

OcrResult

OCR识别返回的结果，有以下只读属性：

• success {boolean} 是否识别成功
• text {string} 识别文本信息
• words {OcrWord} 识别文本的列表(java.util.List对象)
• timeRequired {number} 识别耗时

OcrWord

OCR识别中的文本。有以下只读属性：

• text {string} 识别的文本
• bounds {Rect} android.graphics.Rect对象，表示文本在图片中的位置和范围
• confidences {number} 0~1之间的浮点数，表示结果的可信度，数值越大结果越可靠

第三方插件

参见章节第三方插件。